---
title: "Checkbox"
description: "Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected."
---

import {checkboxContent} from "@/content/components/checkbox";

# Checkbox

Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

<ComponentLinks component="checkbox" reactAriaHook="useCheckbox" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add checkbox",
    npm: "npm install @heroui/checkbox",
    yarn: "yarn add @heroui/checkbox",
    pnpm: "pnpm add @heroui/checkbox",
    bun: "bun add @heroui/checkbox"
  }}
/>


## Import

<ImportTabs
  commands={{
    main: 'import {Checkbox} from "@heroui/react";',
    individual: 'import {Checkbox} from "@heroui/checkbox";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={checkboxContent.usage} />

### Disabled

<CodeDemo title="Disabled" files={checkboxContent.disabled} />

### Sizes

<CodeDemo title="Sizes" files={checkboxContent.sizes} />

### Colors

<CodeDemo title="Colors" files={checkboxContent.colors} />

### Radius

<CodeDemo title="Radius" files={checkboxContent.radius} />

### Indeterminate

The `isIndeterminate` prop sets a `Checkbox` to an indeterminate state, overriding its appearance and maintaining it until set to `false`, regardless of user interaction.

<CodeDemo title="Indeterminate" files={checkboxContent.indeterminate} />

### Line Through

<CodeDemo title="Line Through" files={checkboxContent.lineThrough} />

### Custom Check Icon

> By default, `IconProps` will be passed to your icon component.  Please make sure that `isSelected`, `isIndeterminate`, and `disableAnimation` are not passed to a DOM element.

<CodeDemo title="Custom Check Icon" files={checkboxContent.customCheckIcon} />

### Controlled

<CodeDemo title="Controlled Checkbox" files={checkboxContent.controlled} />

> **Note**: HeroUI `Checkbox` also supports native events like `onChange`, useful for form libraries
> such as [Formik](https://formik.org/) and [React Hook Form](https://react-hook-form.com/).

## Slots

- **base**: Checkbox wrapper, it handles alignment, placement, and general appearance.
- **wrapper**: An inner container that includes styles for relative positioning, flex properties, overflow handling and managing hover and selected states.
- **hiddenInput**: The hidden input element that is used to handle the checkbox state.
- **icon**: Icon within the checkbox, controlling size, visibility, and changes when checked.
- **label**: The text associated with the checkbox.

### Custom Styles

You can customize the `Checkbox` component by passing custom Tailwind CSS classes to the component slots.

<CodeDemo title="Custom Styles" files={checkboxContent.customStyles} />

### Custom Implementation

In case you need to customize the checkbox even further, you can use the `useCheckbox` hook to create your own implementation.

<CodeDemo title="Custom Implementation" files={checkboxContent.customImplementation} />

> **Note**: We used [Tailwind Variants](https://www.tailwind-variants.org/) to implement the styles above, you can use any other library such as [clsx](https://www.npmjs.com/package/clsx) to achieve the same result.

<Spacer y={4} />

## Data Attributes

`Checkbox` has the following attributes on the `base` element:

- **data-selected**:
  When the checkbox is checked. Based on `isSelected` prop.
- **data-pressed**:
  When the checkbox is pressed. Based on [usePress](https://react-spectrum.adobe.com/react-aria/usePress.html)
- **data-invalid**:
  When the checkbox is invalid. Based on `validationState` prop.
- **data-readonly**:
  When the checkbox is readonly. Based on `isReadOnly` prop.
- **data-indeterminate**:
  When the checkbox is indeterminate. Based on `isIndeterminate` prop.
- **data-hover**:
  When the checkbox is being hovered. Based on [useHover](https://react-spectrum.adobe.com/react-aria/useHover.html)
- **data-focus**:
  When the checkbox is being focused. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).
- **data-focus-visible**:
  When the checkbox is being focused with the keyboard. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).
- **data-disabled**:
  When the checkbox is disabled. Based on `isDisabled` prop.
- **data-loading**:
  When the checkbox is loading. Based on `isLoading` prop.

<Spacer y={4} />

## Accessibility

- Built with a native HTML `<input>` element.
- Full support for browser features like form autofill.
- Keyboard focus management and cross browser normalization.
- Keyboard event support for <Kbd>Tab</Kbd> and <Kbd>Space</Kbd> keys.
- Labeling support for assistive technology.
- Indeterminate state support.

<Spacer y={4} />

## API

### Checkbox Props

<APITable
  data={[
    {
      attribute: "children",
      type: "ReactNode",
      description: "The label of the checkbox.",
      default: "-"
    },
    {
      attribute: "icon",
      type: "CheckboxIconProps",
      description: "The icon to be displayed when the checkbox is checked.",
      default: "-"
    },
    {
      attribute: "value",
      type: "string",
      description: "The value of the checkbox element, used when submitting an HTML form.",
      default: "-"
    },
    {
      attribute: "name",
      type: "string",
      description: "The name of the checkbox element, used when submitting an HTML form.",
      default: "-"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The size of the checkbox.",
      default: "md"
    },
    {
      attribute: "color",
      type: "default | primary | secondary | success | warning | danger",
      description: "The color of the checkbox.",
      default: "primary"
    },
    {
      attribute: "radius",
      type: "none | sm | md | lg | full",
      description: "The radius of the checkbox.",
      default: "-"
    },
    {
      attribute: "lineThrough",
      type: "boolean",
      description: "Whether the label should be crossed out.",
      default: "false"
    },
    {
      attribute: "isSelected",
      type: "boolean",
      description: "Whether the element should be selected (controlled).",
      default: "-"
    },
    {
      attribute: "defaultSelected",
      type: "boolean",
      description: "Whether the element should be selected (uncontrolled).",
      default: "-"
    },
    {
      attribute: "isRequired",
      type: "boolean",
      description: "Whether user checkbox is required on the checkbox before form submission.",
      default: "false"
    },
    {
      attribute: "isReadOnly",
      type: "boolean",
      description: "Whether the checkbox can be selected but not changed by the user.",
      default: "-"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the checkbox is disabled.",
      default: "false"
    },
    {
      attribute: "isIndeterminate",
      type: "boolean",
      description: "Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.",
      default: "-"
    },
    {
      attribute: "isInvalid",
      type: "boolean",
      description: "Whether the checkbox is invalid.",
      default: "false"
    },
    {
      attribute: "validationState",
      type: "valid | invalid",
      description: "Whether the checkbox should display its \"valid\" or \"invalid\" visual styling. (Deprecated) use isInvalid instead.",
      default: "-"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether the animation should be disabled.",
      default: "false"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\"｜ \"wrapper\"｜ \"icon\"｜ \"label\", string>>",
      description: "Allows to set custom class names for the checkbox slots.",
      default: "-"
    }
  ]}
/>

### Checkbox Events

<APITable
  data={[
    {
      attribute: "onChange",
      type: "React.ChangeEvent<HTMLInputElement>",
      description: "Handler that is called when the element's selection state changes. You can pull out the new checked state by accessing event.target.checked (boolean).",
      default: "-"
    },
    {
      attribute: "onValueChange",
      type: "(isSelected: boolean) => void",
      description: "Handler that is called when the element's selection state changes.",
      default: "-"
    }
  ]}
/>

### Types

#### Checkbox Icon Props

```ts
type IconProps = {
  "data-checked": string;
  isSelected: boolean;
  isIndeterminate: boolean;
  disableAnimation: boolean;
  className: string;
};

type CheckboxIconProps = ReactNode | ((props: IconProps) => ReactNode);
```
